home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / async11.com / ASYNC.DOC < prev    next >
Encoding:
Text File  |  1989-05-04  |  13.3 KB  |  288 lines
  1.                                     ASYNC11
  2.         Asyncronous Serial Communications Package for Turbo Pascal V5.0
  3.                              Version 1.1 - 05/04/89
  4.                  Copyright (C) 1989, Rising Edge Data Services
  5.  
  6. ASYNC11 is a full-featured Turbo Pascal UNIT that provides interrupt-driven
  7. serial communication PC-compatable computers utilizing standard serial port
  8. hardware (INS 8250's or equivalent).  Unlike similar offerings for Pascal
  9. programmers, ASYNC11 supports full input and output buffering for up to 4
  10. ports operating CONCURRENTLY, with optional full hardware and/or software
  11. handshaking.  In addition, key high-demand subroutines as well as the int-
  12. errupt driver are implimented in assembly language for maximum performance.
  13. Baud rates to 115200 are supported, as well as non-standard rates and all
  14. possible wordsize/parity/stopbit combinations allowed by the 8250 UART.
  15.  
  16. Features -- Version 1.1
  17. =======================
  18.  
  19. *  Supports up to 4 ports simultaneously.
  20. *  Completely interrupt driven I/O for greatest efficiency.
  21. *  Assembly language used for the interrupt driver and key high-performance
  22.    procedures and functions maximize throughput.
  23. *  Created as a Turbo Pascal UNIT for ease of use.
  24. *  Tight, well-commented, structured code for ease of modification/enhancement.
  25.    Includes both Pascal and Assembly source.
  26. *  Supports both hardware (RTS/CTS) and software (XON/XOFF) handshaking,
  27.    at the user's option.
  28. *  28 procedures and functions in all to minimize programmer design time.
  29.  
  30. ASYNC11 supports the serial ports mapped at the following addresses and hard-
  31. ware interrupt lines:
  32.  
  33. Port#  Address  Interrupt
  34. -----  -------  ---------
  35. COM1    03F8h       4
  36. COM2    02F8h       3
  37. COM3    03E8h       4
  38. COM4    02E8h       3
  39.  
  40. The port addresses may be reassigned by changing the contents of the global
  41. constant array C_PortAddr.  For example, to map COM3 at address 3D8h, you
  42. might code it like this (should be done before OpenCom is called) :
  43.  
  44. C_PortAddr[3] := $3D8;
  45.  
  46. To change interrupt priorities (i.e. which hardware interrupt line a port
  47. uses), change the appropriate element in the global constant array
  48. C_PortInt.  For example, if COM1 is wired to use INT5, make the following
  49. assignment (before calling OpenCom):
  50.  
  51. C_PortInt[1] := 5;
  52.  
  53. Finally, the number of ports supported can be changed, although recompilation
  54. of the unit is nessesary in this case.  Load the unit and change the constant
  55. C_MaxPort to the highest available port.  Then fill in the defaults for
  56. C_PortAddr and C_PortInt as appropriate and recompile the unit.
  57.  
  58. ASYNC11 will most likely NOT work with multiport boards (like the GTEK PCSS-4
  59. and -8 models) that use one standard COM port address to "multiplex" 2 or more
  60. ports.  ASYNC11 WILL support the "currently active port" on such boards, but
  61. does NOT support the port switching mechanisim nessesary for full utilization
  62. of these boards, although it may be possible to modify the code for this.
  63.  
  64. Available procedures and functions
  65. ==================================
  66.  
  67. User-accessable procedures and functions will be listed below along with a
  68. concise explaination of their function.  For more complete documentation and
  69. revision information, refer to the Pascal source code.
  70.  
  71. In all cases:  ComPort = Port # to use, range = 1 to C_MaxPort (usually 4).
  72.  
  73. Procedure ClearCom(ComPort:Byte; IO:Char);
  74.   - Clear input (IO='I'), output (IO='O') or both (IO='B') buffers
  75.  
  76. Procedure CloseCom(ComPort:Byte);
  77.   - Close a port previously opened for I/O
  78.  
  79. Procedure CloseAllComs;
  80.   - Close ALL active ports
  81.  
  82. Function ComBufferLeft(ComPort:Byte; IO:Char) : Word;
  83.   - Returns #bytes free in the input (IO='I') or output (IO='O') buffers
  84.  
  85. Function ComExist(ComPort:Byte) : Boolean;
  86.   - Performs a hardware-based test to determine if a port exists
  87.  
  88. Function ComReadCh(ComPort:Byte) : Char;
  89.   - Get one character from the selected input buffer
  90.  
  91. Function ComReadChW(ComPort:Byte) : Char;
  92.   - Get one character from the selected input buffer, wait for it if nessesary
  93.  
  94. Procedure ComReadln(ComPort:Byte; Var St:String; Size:Byte; Echo:Boolean);
  95.   - Get a string from the selected port.  Echoback & simple editing supported
  96.  
  97. Function ComTrueBaud(Baud:Longint) : Real;
  98.   - Compute actual baud rate that the hardware will transmit at
  99.  
  100. Procedure ComParams(ComPort:Byte; Baud:LongInt; WordSize:Byte; Parity:Char; StopBits:Byte);
  101.   - Set baud rate, word size, parity and stop bit options for selected port
  102.  
  103. Procedure ComWaitForClear(ComPort:Byte);
  104.   - Suspend execution until selected port's output buffer is clear
  105.  
  106. Procedure ComWrite(ComPort:Byte; St:String);
  107.   - Send a string out the selected port (place in output buffer)
  108.  
  109. Procedure ComWriteCh(ComPort:Byte; Ch:Char);
  110.   - Place a character in the output buffer of the selected port
  111.  
  112. Procedure ComWriteChW(ComPort:Byte; Ch:Char);
  113.   - Place character in output buffer, waiting for buffer space if nessesary.
  114.  
  115. Procedure ComWriteln(ComPort:Byte; St:String);
  116.   - Send string out selected port with appended CR/LF.
  117.  
  118. Procedure ComWriteWithDelay(ComPort:Byte; St:String; Dly:Word);
  119.   - Send string out selected port, delaying between character transmissions
  120.  
  121. Function CTSStat(ComPort:Byte) : Boolean;
  122.   - Returns status of RS232 "Clear To Send" (CTS) signal line (pin 5)
  123.  
  124. Function DCDStat(ComPort:Byte) : Boolean;
  125.   - Returns status of RS232 "Data Carrier Detect" (DCD) signal line (pin 8)
  126.  
  127. Function DSRStat(ComPort:Byte) : Boolean;
  128.   - Returns status of RS232 "Data Set Ready" (DSR) signal line (pin 6)
  129.  
  130. Function OpenCom(ComPort:Byte; InBufferSize,OutBufferSize:Word) : Boolean;
  131.   - Prepares communications system for I/O on selected port
  132.  
  133. Function RIStat(ComPort:Byte) : Boolean;
  134.   - Returns status of RS232 Ring Indicator (RI) signal line (pin 22)
  135.  
  136. Procedure SetCTSMode(ComPort:Byte; Mode:Boolean);
  137.   - Enables or disables built-in CTS hardware handshaking for transmission
  138.  
  139. Procedure SetDTR(ComPort:Byte; Assert:Boolean);
  140.   - Provides control for the RS232 "Data Terminal Ready" (DTR) line (pin 20)
  141.  
  142. Procedure SetOUT1(ComPort:Byte; Assert:Boolean);
  143.   - Controls logic level (ASSERT=TRUE for low level) of 8250 OUT1 signal line
  144.  
  145. Procedure SetOUT2(ComPort:Byte; Assert:Boolean);
  146.   - Controls logic level (ASSERT=TRUE for low level) of 8250 OUT2 signal line.
  147.     Used as a redundant mechanisim for controlling 8250 interrupts on PC's.
  148.  
  149. Procedure SetRTS(ComPort:Byte; Assert:Boolean);
  150.   - Provides control for the RS232 "Request To Send" (RTS) line (pin 4)
  151.     Note: Avoid using this procedure if automatic RTS handshaking enabled.
  152.  
  153. Procedure SetRTSMode(ComPort:Byte; Mode:Boolean; RTSOn,RTSOff:Word);
  154.   - Enables or disables RTS hardware handshake for reception
  155.     Also controls assert/unassert points when enabled.
  156.  
  157. Procedure SoftHandshake(ComPort:Byte; Mode:Boolean; Start,Stop:Char);
  158.   - Enables or disables XON/XOFF software handshake (transmission ONLY).
  159.     Also allows XON/XOFF characters to be redefined.
  160.  
  161. Variable(s)             Type            Function
  162. ----------------------  --------------  ----------------------------------
  163. C_InBufPtr,C_OutBufPtr  C_PointerArray  Input/output buffer pointers
  164. C_InHead,C_OutHead      C_WordArray     Input/output head pointers
  165. C_InTail,C_OutTail      C_WordArray     Input/output tail pointers
  166. C_InSize,C_OutSize      C_WordArray     Input/output buffer sizes
  167. C_RTSOn,C_RTSOff        C_WordArray     RTS assert/drop buffer points
  168. C_StartChar,C_StopChar  C_CharArray     Soft hndshake start/stop char
  169. C_Status,C_Ctrl         C_ByteArray     STATUS and CONTROL registers
  170. C_PortOpen              C_BooleanArray  Port open/close flags
  171. C_PortAddr              C_WordArray     Base address of 8250 UART for port
  172. C_PortInt               C_ByteArray     Hard INT line used by UART for port
  173.  
  174. Status byte definition (C_Status):
  175.   7   6   5   4   3   2   1   0
  176.   |   |   |   |   |   |   |   |____ Input buffer empty
  177.   |   |   |   |   |   |   |________ Input buffer full
  178.   |   |   |   |   |   |____________ Output buffer empty
  179.   |   |   |   |   |________________ Output buffer full
  180.   |   |   |   |____________________ Input buffer overflow
  181.   |   |   |________________________ Output buffer overflow
  182.   |   |____________________________ Hard handshake active (xmit stopped)
  183.   |________________________________ Soft handshake active (xmit stopped)
  184.  
  185. Control byte definition (C_Ctrl):
  186.   7   6   5   4   3   2   1   0
  187.   |   |   |   |   |   |   |   |____ Enable RTS handshake
  188.   |   |   |   |   |   |   |________ Enable CTS handshake
  189.   |   |   |   |   |   |____________ Enable software handshake (xmit only)
  190.   |   |   |   |   |________________
  191.   |   |   |   |____________________
  192.   |   |   |________________________
  193.   |   |____________________________
  194.   |________________________________ Pyrotronics XL3 mode (do not use!)
  195.  
  196. Files in archive:
  197. -----------------
  198. ASYNC.PAS     - Pascal unit source code
  199. ASYNC.ASM     - Assembly source for external routines and communications ISR
  200. ASYNC.DOC     - This file
  201. ASYNC.OBJ     - Assembled ASYNC.ASM
  202. ASYNC.TPU     - Compiled ready-to-use Turbo Pascal V5.0 UNIT
  203.  
  204. Note to Assembly-language programmers:  The ASYNC.ASM source file was assembled
  205. using Borland's Turbo Assembler (V1.0).  Since the assembler's IDEAL mode
  206. was used throught, it will require some modifications to the source to get it
  207. to assemble properly with MASM.
  208.  
  209. ==============================================================================
  210.  
  211. DISCLAIMER and USAGE AGREEMENT:
  212.  
  213. Yes, this is the place where the standard batch of legalese goes.  When trans-
  214. lated into English it usually boils down to "Use of this program is your
  215. responsibility and not ours".  Effort has been made to provide software that
  216. is beleived to function as documented, but no guarantees can be made as to
  217. whether or not it will ever work out for you.  If this software malfunctions
  218. and, let's say your house or business burns down or blows itself up because
  219. of that malfunction, you're responsible for covering the loss -- not us.
  220. In short, if you use this software, and you experience loss and/or inconven-
  221. ience because of it, tough! (And if the world were populated exclusively by
  222. reasonable people, instead of those types that file lawsuits whenever someone
  223. looks at them the wrong way, time- and space-wasting statements like this
  224. would be unnessesary).
  225.  
  226. Permission is hereby granted to distribute this package (the "software" ) to
  227. friends, over information networks or through public-domain distribution houses
  228. provided this documentation accompanies it.  This software may NOT be
  229. distributed for profit or monetary gain (other than the single-disk asking
  230. price of a shareware distributor used to cover duplication and distribution
  231. costs, not to exceed $10 in any event).  Rising Edge Data Services reserves
  232. all copyrights in regard to the software and the accompanying documentation
  233. and may change the software without notice.
  234.  
  235. With that out of the way, your comments, suggestions, bug reports (and
  236. donations, $20 suggested) are welcome.  Any donations will be used to finance
  237. improvements to this and other forthcoming modules.
  238.  
  239. You may reach me in the following ways:
  240.  
  241. Via US Mail:                           Via Modem
  242. ------------------------               ---------------------------
  243. Mark L. Schultz                        Best Power Technology BBS
  244. Rising Edge Data Services              Necedah, WI  USA
  245. 201 Liberty St. Apt. #4                User name: Mark Schultz (or SYSOP)
  246. Mauston, WI  USA 53948                 Phone: (608) 565-7424
  247. Voice: (608) 847-4287
  248.  
  249. I can also be reached at the Exec-PC multiuser BBS based in Milwaukee, WI USA
  250. Phone: 414-964-5160.  Username: Best Power
  251.  
  252. ==============================================================================
  253.  
  254.          ----------------end-of-author's-documentation---------------
  255.  
  256.                         Software Library Information:
  257.  
  258.                    This disk copy provided as a service of
  259.  
  260.                         The Public (Software) Library
  261.  
  262.          We are not the authors of this program, nor are we associated
  263.          with the author in any way other than as a distributor of the
  264.          program in accordance with the author's terms of distribution.
  265.  
  266.          Please direct shareware payments and specific questions about
  267.          this program to the author of the program, whose name appears
  268.          elsewhere in  this documentation. If you have trouble getting
  269.          in touch with the author,  we will do whatever we can to help
  270.          you with your questions. All programs have been tested and do
  271.          run.  To report problems,  please use the form that is in the
  272.          file PROBLEM.DOC on many of our disks or in other written for-
  273.          mat with screen printouts, if possible.  The P(s)L cannot de-
  274.          bug programs over the telephone.
  275.  
  276.          Disks in the P(s)L are updated monthly, so if you did not get
  277.          this disk  directly from the P(s)L,  you should be aware that
  278.          the files in this set may no  longer be the current versions.
  279.  
  280.          For a copy of the latest monthly software library newsletter
  281.          and a list of the 1,800+ disks in the library, call or write
  282.  
  283.                         The Public (Software) Library
  284.                               P.O.Box 35705 - F
  285.                            Houston, TX 77235-5705
  286.                                (713) 665-7017
  287.  
  288.